Article

2026-07-09 Arkon Fullstack Challenge V1 PRD

临时-Arkon Challenge

Arkon Fullstack Challenge V1 PRD

文档编号：AFSC-PRD-V1

日期：2026-07-09

关联文档：

1. 文档目标与版本范围

Arkon Fullstack Challenge V1 的目标不是做一个功能庞杂的健康产品，而是交付一个范围克制、链路完整、工程质量清晰可验收的评估漏斗 Demo。

这一版只完成一件事：

让评审方在较短时间内完整走完 “进入页面 -> 自动建会话 -> 分步保存 -> 刷新恢复 -> 提交评估 -> 免费预览 -> 解锁完整结果” 的闭环，并在过程中感受到这是一个经过产品化收口和工程化验证的实现，而不是临时拼接页面。

本版本不追求复杂视觉设计，不追求真实支付，不追求大而全的运营后台。核心判断标准是：

  1. 链路是否完整
  2. 状态是否可恢复
  3. 校验是否像一个可交付产品
  4. 服务端边界是否明确
  5. 是否具备本地自动化自测能力

2. 产品定位

本项目定位为：

用于面试场景展示全栈工程能力的轻量级评估漏斗 Demo

它的主要职责不是提供真实商业价值，而是让评审方快速看到以下能力是否成立：

  1. 会话与草稿管理能力
  2. 前后端分层能力
  3. 服务端计算与门控能力
  4. 子路径部署兼容能力
  5. 自动化回归意识

本版本确定以下产品原则：

  1. 前台流程必须足够短，评审在 1 至 3 分钟内应能完成主要体验。
  2. 每一步都必须可保存，不能只依赖最终一次性提交。
  3. 结果必须由服务端计算，不能只在前端拼装“看起来像结果”的假数据。
  4. 免费态与解锁态必须有明确差异，体现业务门控思路。
  5. 输入错误必须有友好提示，不允许原始异常直接暴露在 UI 上。
  6. 本地环境必须可被脚本完整回归。

3. 目标用户与使用场景

本产品的主要使用场景不是面向真实终端用户，而是面向技术评审和候选人讲解。

3.1 评审使用场景

评审打开页面后，期望完成以下动作：

  1. 看到页面能够自动开始工作，而不是需要先登录或手动初始化。
  2. 在四步内完成一次完整填写。
  3. 中途刷新后，验证草稿确实恢复。
  4. 看到结果不是一次性静态文本，而是服务端产出的结构化结果。
  5. 通过模拟支付看到结果门控切换。

3.2 候选人讲解场景

候选人在讲解项目时，应当能够围绕以下内容展开：

  1. 为什么选择分步保存
  2. 为什么把计算逻辑放在服务端
  3. 为什么要支持 base path
  4. 为什么免费态和解锁态要做成两个层次
  5. 为什么要用 Playwright 做回归

4. 产品范围与页面边界

本版本只包含两个用户前台页面：

  1. 漏斗首页：/
  2. 结果页：/result/[sessionId]

在部署态下，通过 base path 暴露为：

  • /labs/arkon-challenge
  • /labs/arkon-challenge/result/[sessionId]

本版本不新增：

  • 登录页
  • 个人中心
  • 支付页
  • 管理后台
  • 历史记录页
  • 多问卷列表页

5. 核心业务流程

5.1 首页进入

用户进入首页后，系统自动检查 localStorage 中是否存在本地会话标识。

系统行为分两种：

  1. 如果没有本地标识，则自动调用 POST /api/session 创建新会话。
  2. 如果存在本地标识，则自动请求服务端恢复该会话。

如果本地标识已失效，系统必须：

  1. 清理旧 localStorage 值
  2. 自动创建新会话
  3. 避免用户卡死在不可恢复状态

5.2 四步问卷

第一步：身份信息

  • 用户选择性别
  • 未选择时不能继续

第二步：身体数据

  • 用户填写年龄
  • 用户填写身高
  • 用户填写当前体重
  • 所有字段需进行范围校验

第三步：目标设置

  • 用户选择主要目标
  • 用户填写目标体重
  • 目标体重需进行范围校验
  • 目标体重不能高于当前体重 20kg 以上

第四步：活动水平

  • 用户选择活动水平
  • 提交前必须确保该步骤也已保存

5.3 结果页

用户完成提交后，进入结果页。

结果页必须区分两种状态：

  1. 免费预览态
  2. 解锁完整态

免费预览态可以展示：

  • BMI
  • BMI 分类
  • 简要叙述

免费预览态必须隐藏：

  • 推荐热量
  • 每周节奏
  • 目标日期

解锁完整态需展示全部结果字段。

5.4 模拟支付

本版本不接入真实支付。

结果页提供一个明确按钮：

  • Simulate pay callback

点击后触发模拟支付回调，系统把当前 session 的订阅状态切换为 ACTIVE，并重新读取结果页数据。

6. 功能模块定义

6.1 会话模块

负责以下能力：

  1. 自动创建公开 session
  2. 通过 localStorage 记住当前会话
  3. 通过服务端恢复草稿
  4. 当旧 session 失效时自动重建

6.2 分步保存模块

负责以下能力：

  1. 每一步单独保存
  2. 每一步仅提交当前步骤需要的字段
  3. 保存成功后推进到下一步
  4. 保存失败后展示可读错误

6.3 表单校验模块

负责以下能力：

  1. 前端基础校验
  2. 服务端兜底校验
  3. 字段级错误提示
  4. 全局状态提示

该模块必须满足以下要求：

  1. 用户能知道哪个字段错了
  2. 用户能知道为什么错了
  3. 页面上不能出现原始 schema issue 数组

6.4 服务端评估模块

负责以下能力：

  1. 在提交时校验所需字段是否完整
  2. 根据用户输入计算 BMI、热量建议、每周节奏、目标日期与叙述
  3. 将结果持久化

6.5 结果门控模块

负责以下能力：

  1. 免费态只返回可见字段
  2. 解锁态返回完整字段
  3. 结果页根据订阅状态切换展示

6.6 模拟支付模块

负责以下能力：

  1. 人工触发一个最简化支付回调
  2. 将当前 session 订阅状态切换为 ACTIVE
  3. 支付后不丢失结果、不重置问卷

7. 功能范围说明

7.1 范围内

本版本明确包含：

  1. 会话创建
  2. 会话恢复
  3. 分步保存
  4. 四步问卷
  5. 服务端结果计算
  6. 免费态结果展示
  7. 模拟支付解锁
  8. 本地自动化自测
  9. base path 兼容

7.2 范围外

本版本明确不做：

  1. 真实支付网关接入
  2. 登录与账号体系
  3. 多问卷管理后台
  4. 运营配置后台
  5. 历史订单与支付流水页
  6. 多语言产品设计
  7. 复杂权限系统

8. 关键交互规则

8.1 状态反馈

页面必须始终有状态反馈，例如：

  • 正在创建会话
  • 正在恢复草稿
  • 正在保存进度
  • 正在生成评估结果

8.2 错误反馈

错误反馈分为两层：

  1. 全局状态提示
  2. 字段级提示

例如：

  • 年龄必须在 18 到 80 岁之间
  • 身高必须在 130 到 230 厘米之间
  • 请先选择活动水平再提交

8.3 返回行为

  • 第二步可返回第一步
  • 第三步可返回第二步
  • 第四步可返回第三步
  • 结果页可返回漏斗首页

8.4 刷新行为

用户在第二步、第三步或第四步刷新页面后，系统必须尽量恢复到最近一次已保存的步骤，而不是强制回到第一步。

9. 数据项与业务规则

9.1 必填字段

最终提交前必须具备以下字段：

  1. sex
  2. age
  3. heightCm
  4. weightKg
  5. goal
  6. targetWeightKg
  7. activityLevel

9.2 范围规则

  • age：18 到 80
  • heightCm：130 到 230
  • weightKg：35 到 250
  • targetWeightKg：35 到 250

9.3 特殊业务约束

  • targetWeightKg 不能高于 weightKg + 20

9.4 结果门控规则

免费态隐藏字段固定为：

  1. recommendedKcal
  2. weeklyDeltaKg
  3. targetDateIso

10. 非功能性要求

10.1 可运行性

  • 项目必须能在本地通过 Next.js 正常启动
  • 项目必须支持自定义端口运行

10.2 可部署性

  • 项目必须兼容 /labs/arkon-challenge 子路径部署
  • 不允许前端硬编码根路径请求导致子路径部署失效

10.3 可测试性

  • 服务层应具备单元测试能力
  • 浏览器层应具备 Playwright 回归能力
  • 本地应可执行 60 条回归用例

10.4 可维护性

  • 前后端边界应清晰
  • 页面逻辑、服务逻辑、仓储逻辑应分层
  • 错误提示应可持续扩展，而不是散落在页面字符串中

11. 接口范围

本版本包含以下接口：

  • POST /api/session
  • GET /api/session/:sessionId
  • PATCH /api/session/:sessionId/progress
  • POST /api/session/:sessionId/submit
  • GET /api/session/:sessionId/result
  • POST /api/pay

12. 产品验收标准

本版本以以下标准作为验收口径：

  1. 首页可自动创建或恢复会话
  2. 四步流程可完整走通
  3. 每一步均可分步保存
  4. 刷新后可恢复到最近已保存步骤
  5. 非法输入会显示友好提示
  6. 最终提交后可进入结果页
  7. 免费态与解锁态结果差异明确
  8. 模拟支付后结果可解锁
  9. 子路径下所有链路正常
  10. 本地自动化自测全部通过

13. 风险与约束

13.1 主要风险

  1. 子路径部署下请求路径和跳转路径出错
  2. 分步保存和最终提交逻辑不一致
  3. 校验提示不友好，影响交付观感
  4. 最终提交漏保存最后一步数据

13.2 对应约束

  1. fetch、Link、redirect 必须统一考虑 base path
  2. 提交前必须补保存第四步
  3. 前后端都要参与校验，但页面只展示友好信息
  4. 本地必须保留完整回归脚本作为交付证据